From 63a4326afff560b7e301ccaffd68838983949bc6 Mon Sep 17 00:00:00 2001 From: tsteven4 <13596209+tsteven4@users.noreply.github.com> Date: Sat, 23 Oct 2021 12:51:48 -0600 Subject: [PATCH] update document. (#741) update build chapter to reflect current builds. update dtd to 4.5. correct manual page document syntax and missing items. --- xmldoc/chapters/build.xml | 280 +++++++++++++++++++++++++++++++++----- xmldoc/gpsbabel_man.xml | 23 +++- xmldoc/readme.xml | 12 +- 3 files changed, 267 insertions(+), 48 deletions(-) diff --git a/xmldoc/chapters/build.xml b/xmldoc/chapters/build.xml index d327199de..b1fd548a6 100644 --- a/xmldoc/chapters/build.xml +++ b/xmldoc/chapters/build.xml @@ -16,12 +16,12 @@ additional information. Building from source. - For operating systems where no binary is provided or if + For operating systems where no binary is provided, or if you want the latest development version, you will have to build it from source. The code should be compilable on any system with -ISO C++14. It's tested on Linux, Mac OS/X, and Windows cross compilers. -Less frequently, someone will build on MSVC, FreeBSD, OpenBSD, Solaris, -etc. Both Clang/LLVM and GNU C++ are regularly exercised via automation. +ISO C++17. It's tested on Ubuntu, macOS, and Windows. +Less frequently, someone will build on FreeBSD, OpenBSD, Solaris, +etc. Clang/LLVM, GNU C++, and MSVC are regularly exercised via automation. You can grab a release from the GPSBabel download page, but if you're going to be doing any development, you'll find that working from the GPSBabel Github repo is easier. Checkouts via Git, HTTPS, SSH, and Subversion are supported. @@ -33,7 +33,7 @@ You can grab a release from the Qt -Qt version 5.9 or newer is required for all builds. MacOS and Windows users can download +Qt version 5.12 or newer is required for all builds. MacOS and Windows users can download binaries from Qt Downloads Fedora or CentOS users may need to 'yum install qt-devel'. Optionally, use qt5-base. When in doubt, 'yum search qt' or 'yum search qt5' may help you find the correct package name. Ubuntu users may need to 'apt-get install qtbase5-dev'. Package names and versions in Linux frequently change, so you may need to ask your Linux vendor @@ -45,12 +45,12 @@ use Docker. - libusb + libusb 1.0 is needed to communicate with use with older USB Garmins. -For MacOS, we use an included copy. +For macOS, we use an included copy. Fedora users may need to 'yum install libusb-devel'. Ubuntu users may need to 'apt install libusb-dev' or look in tools/Docker* for inspiration from our automated Docker builds. @@ -81,7 +81,7 @@ from our automated Docker builds. editor and debugger. Its use is strongly encouraged for those new to C++. Once you have Qt correctly installed, just opening either the GPSBabel.pro or gui/app.pro files from - the OS file launcher (e.g. a double click in MacOS while seeing it in Finder) + the OS file launcher (e.g. a double click in macOS while seeing it in Finder) or from a File->Open in an already-running instance of Qt Creator is the fastest and easiest way for most people to get to development because it handles things like build dependencies changing and class and method compilation. @@ -95,41 +95,251 @@ from our automated Docker builds. Building with configure - Those familiar with UNIX-y open source packages may be more comfortable - with configure. In most cases, the code is as simple to build as running: +The GNU Build System (configure) is no longer suppored and has +been removed. For command line builds please use qmake. - ./configure && make - + + + Building with cmake + +The use of cmake is experimental. The implementation is not complete. It is +untested by continuous integration. It is not recommended for production use. - -There are additional flags that can be passed to configure to - customize your build of GPSBabel. + + + Building with qmake + +Those familiar with the command line may be more comfortable +using qmake from the command line. In most cases, the code is as simple to build as running: -./configure --help - -lists all the supported options, but of interest we have: - Excludes the shapefile support. + + qmake && make + + +Two build methods are supported with MSVC tools. - - Excludes all support for our something-separated formats. + + +To create a visual studio project that can be built with msbuild: +qmake -tp vc + + +To create a Makefile that can be built with nmake: +qmake + + + - - Excludes all filter support. + There are additional flags that can be passed to qmake to +customize your build of GPSBabel. - - dir Specifies that the doc should be created and installed in dir. + + + WITH_LIBUSB=no|pkgconfig|system*|included*|custom + + +note that libusb is NOT used on windows. - - Disables use of libusb, even it's it's available. + + + no + + build without libusb-1.0. functionality will be limited. + + + + pkgconfig + + build with libusb-1.0 found by pkg-config. + + + + system + + build with libusb-1.0 found on system library path and under +libusb-1.0 on system include path (default, linux, openbsd). + + + + included + + build with libusb-1.0 included with gpsbabel (default, macOS only). + + + + custom + + build with user supplied libusb-1.0. LIBS and INCLUDEPATH may need to +be set, e.g. LIBS+=... INCLUDEPATH+=... + + + + + + + WITH_SHAPELIB=no|pkgconfig|included*|custom + + + + no + + build without shapelib. functionality will be limited. + + + + pkgconfig + + build with shapelib found by pkg-config. + + + + included + + build with shapelib included with gpsbabel (default). + + + + custom + + build with user supplied shapelib. LIBS and INCLUDEPATH may need to +be set, e.g. LIBS+=... INCLUDEPATH+=... + + + + + + + WITH_ZLIB=no|pkgconfig|included*|custom + + + + no + + build without zlib. functionality will be limited. + + + + pkgconfig + + build with zlib found by pkg-config. + + + + included + + build with zlib included with gpsbabel (default). + + + + custom + + build with user supplied zlib. LIBS and INCLUDEPATH may need to be +set, e.g. LIBS+=... INCLUDEPATH+=... + + + + + + + CONFIG+=disable-mappreview + + +This options disables the map preview feature. With the feature disabled +QtWebEngine and QtWebEngineWdigets are not used. Note that QtWebKit and +QtWebKitWidgets are not longer supported. - - By default, we use our own version of zlib. If you specify the system zlib is used. A value of (or --without-zlib) disables zlib. + + + + DOCVERSION=... + + +string appended to documentation location for www.gpsbabel.org. The default +value is the version string, e.g. "1.7.0". This is used by the gpsbabel.org +target, you are unlikely to need it unless you are maintaining +www.gpsbabel.org. - - There are some makefile targets that are useful mostly to the GPSBabel maintainers - that appear only in the configure-generated Makefiles. Their presence is considered - mostly a TODO bug and those items should be migrated to stand-alone tools. - - + + + + WEB=DIR + + +Path where the documentation will be stored for www.gpsbabel.org. This is +used by the gpsbabel.org target, you are unlikely to need it unless you are +maintaining www.gpsbabel.org. The default location is "../babelweb" + + + + + +Additional makefile targets are available for special purposes. + + + + check + + Run the basic test suite. + + + + check-vtesto + + Run valgrind memcheck. + + + + gpsbabel + + Build the command line tool. + + + + gpsbabel.hmtl + + Create the html documentation. + + + + gpsbabel.org + + Create documentation for use on www.gpsbabel.org. + + + + gpsbabel.pdf + + Create the pdf documentation. + + + + gui + + Build the graphical user interface. + + + + unix-gui + + Build the graphical user interface and collect the components for +distribution. On Linux the gpsbabel generated components will be under +gui/GPSBabelFE, any dynamically linked required libraries are not included. +On macOS an app bundle will be created at gui/GPSBabelFE.app and an apple disk +image will be created at gui/GPSBabelFE.dmg. + + + + + + Runtime Dependencies: + +On non-macOS unix builds by default we now compile in the gpsbabel generated +translation files, i.e. gpsbabelfe_*.qm, gpsbabel_*.qm, as well as +gmapbase.html. When compiled in these files do not need to be distributed. +These are used by the GUI. Additional translation files from Qt will also be +used if they are found. They may be in a package such as qttranslations5-l10n +or qt5-qttranslations. + + diff --git a/xmldoc/gpsbabel_man.xml b/xmldoc/gpsbabel_man.xml index 8b833bfc8..ab169c7ce 100644 --- a/xmldoc/gpsbabel_man.xml +++ b/xmldoc/gpsbabel_man.xml @@ -1,10 +1,19 @@ - + PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd'> + + + + + Robert Lipe et al. + + + gpsbabel 1 + GPSBabel + GPSBabel manual gpsbabel @@ -13,7 +22,7 @@ - gpsbabel + gpsbabel @@ -39,7 +48,7 @@ or as the backend for other tools. Options GPSBabel accepts the following options and processes them in order - from left to right.. Additional options are documented in the + from left to right. Additional options are documented in the docbook help. @@ -103,13 +112,13 @@ or as the backend for other tools. - Generate smart names for waypoints on output. + Generate short names for waypoints on output. - format + format Display help that is more exhaustive than this page. If diff --git a/xmldoc/readme.xml b/xmldoc/readme.xml index 06b757d67..e46f2df11 100644 --- a/xmldoc/readme.xml +++ b/xmldoc/readme.xml @@ -1,7 +1,7 @@ - %parts; @@ -11,10 +11,10 @@ > - - GPSBabel Documentation - + + GPSBabel Documentation + - &allchapters; + &allchapters; -- 2.30.2